Skip to main content

Universal App Setup and Running Guide

Prerequisites​

  • Android Studio installed (for Android development)
  • Xcode installed (for iOS development)
  • Node.js and npm installed
  • Android SDK configured (for Android)
  • iOS Simulator set up (for iOS)

Running the App​

1. Create Catalyst App​

npx create-catalyst-app@latest

2. Get Your Local IP Address​

# For macOS
ifconfig | grep "inet " | grep -v 127.0.0.1

# For Linux
ip addr show | grep "inet "

3. Update Configuration​

Set a reachable local IP in WEBVIEW_CONFIG.LOCAL_IP. Use your LAN IP, not localhost.

{
  "WEBVIEW_CONFIG": {
    "LOCAL_IP": "192.168.1.100",
    "port": "3005"
  }
}

4. Set Up Emulator​

5. Build and Run​

# Build web assets
npm run build

In a new terminal:

# For Android debug
npm run buildApp:android

# For iOS
npm run buildApp:ios

Useful Commands​

iOS Simulator Commands​

# List all simulators
xcrun simctl list

# List available runtimes
xcrun simctl list runtimes --json

# Open Simulator app
open -a Simulator

# Shutdown all simulators
xcrun simctl shutdown all

# Boot specific simulator
xcrun simctl boot DEVICE_UUID

# Install app on booted simulator
xcrun simctl install booted /path/to/your/app.app

# Launch app on simulator
xcrun simctl launch booted your.app.bundle.id

Important Notes​

  • The local IP address might change when switching networks
  • Some corporate networks might block required ports
  • iOS build types are case-sensitive: use Debug or Release
  • Keep your SDK tools and development environment updated
  • Ensure WEBVIEW_CONFIG.accessControl.allowedUrls includes every required API or asset domain when access control is enabled

For detailed troubleshooting, see the Universal App FAQ.